VRTC

VRTC 是 Web SDK 中所有可调用方法的入口。

VRTC 可用于创建客户端和音视频流对象，以及一些相关操作。

成员属性

成员函数

成员组件

• Logger

变量说明

VERSION

VERSION: string

当前使用的 SDK 版本号

函数说明

checkSystemRequirements

checkSystemRequirements(): boolean

检查 Web SDK 对正在使用的浏览器的适配情况

返回值

true: Web SDK 与当前使用的浏览器适配 false: Web SDK 与当前使用的浏览器不适配

checkVideoPermission

checkVideoPermission = (onSuccess, onFailure) => {
    return checkVideoPermission(onSuccess, onFailure);
  };

检测是否有摄像头权限

参数

checkAudioPermission

checkAudioPermission = (onSuccess, onFailure) => {
    return checkAudioPermission(onSuccess, onFailure);
  };
  setAid = (aid) => {
    setAid(aid);
  };
  setReportEntry = (key, value) => {
    return setHeader(key, value);
  };

检测是否有麦克风权限

参数

getDevices

getDevices = (onSuccess, onFailure) \=> {
    return  getDevices({(devices: MediaDeviceInfo => void} onSuccess, {(err?: Error) => void} onFailure);
};

获取可用的媒体输入/输出设备，比如麦克风、摄像头、耳机等

参数

MediaDeviceInfo 类型

createClient

createClient = (options) => {
    eventLog('rtc_create_client', { message: JSON.stringify(options) });
    return new Proxy(VClient(options), realClientHander);
  };

创建客户端 参数

返回值 client

createStream

createStream(options: StreamOption): stream

创建音视频流对象 同一个 client 最多可以创建 2 条流，一般是一条摄像头流和一条屏幕流

参数

Option设置

注意

1. 支持对 audio、video 和 screen 进行约束，例如，关闭音频 3A，具体用法和浏览器支持情况请参考 MediaTrackConstraints 说明。
2. microphoneId 和 cameraId 可以从 getDevices 中获取。

返回值

stream

Client

Client 接口提供音视频通话的核心功能，例如加入频道、发布和订阅音视频流等。

你可以通过 createClient 来创建 client 对象。一个 client 对象代表一个本地客户端。

成员函数

函数说明

init

init(appId: string, onSuccess?: () => void, onFailure?: (err: Error) => void): void

client 初始化，核心功能是与信令服务器建立 WebSocket 长连接，是所有后续操作的前提

参数

注意

后续操作都需要以此函数调用为前提。

join

join(token: string, roomId: string, userId: string, onSuccess?: () => void, onFailure?: (err: Error) => void): string

加入房间

参数

返回值

promise<userId>

注意

1. 同一个 client 只可以加入一个房间。

2. token 与 appid 相关，每个项目可以有不同的生成逻辑。

3. 与 leave 为逆操作。

4. 加入大班小课功能后，可以同时创建两个 client 分别进入不同房间，但是只可以在一个房间内推流。

leave

leave(onSuccess?: () => void, onFailure?: (err: Error) => void): promise

离开当前房间

参数

返回值

promise

注意

与 join 为逆操作。

publish

publish(
    stream: StreamInstance,
    option?: publishOption,
    onFailure?: FailureFunction
  ): void;

在房间发布音视频流

参数

publishOption

返回值

promise

注意

1.stream 由 VRTC.createStream 来创建。

2.与 unpublish 为逆操作。

回调

成功推流会触发 stream-published 事件

unpublish

unpublish(byteStream: byteStream, onFailure?: (err: Error) => void): promise

停止推流

参数

返回值

promise

注意

与 publish 为逆操作。

回调

成功之后远端会受到 stream-removed 事件

subscribe

subscribe(byteStream: byteStream, options?: SubscribeOption, onFailure?: (err: Error) => void): promise

订阅远端流

参数

SubscribeOption配置

返回值

promise

回调

成功订阅会触发 stream-subscribed 事件

注意

1.与 unsubscribe 为逆操作。

2.建议配合 stream-added 事件使用。

3.SubscribeOption 中 audio 与 video 不可以同时设置为 false 。

unsubscribe

unsubscribe(byteStream: byteStream, onFailure?: (err: Error) => void): promise

停止订阅

参数

返回值

promise

注意

与 subscribe 为逆操作。

on

const on = (event, callback) => {}

监听事件

参数

注意

与 off 为逆操作。

off

const  off = (event, callback) \=> {}

取消监听事件

参数

注意

与 on 为逆操作。

getConnectionState

getConnectionState(): symbol

获取连接状态

返回值

1.调用 join 之后为 CONNECTING。

2.进入房间成功后为 CONNECTED。

3.调用 leave 之后为 DISCONNECTING。

4.离开房间成功后为 DISCONNECTED。

getLocalVideoStats

getLocalVideoStats(callback: ({ uid: LocalVideoStats }) => void): void

获取本地视频流属性

参数

LocalVideoStats详情

getLocalAudioStats

getLocalAudioStats(callback: ({ uid: LocalAudioStats }) => void): void

获取本地视频流属性

参数

LocalAudioStats详情

getRemoteAudioStats

getRemoteAudioStats(callback: ({ uid: RemoteAudioStats }) => void): void

获取远端视频流属性

参数

RemoteAudioStats详情

getRemoteVideoStats

getRemoteVideoStats(callback: ({ uid: RemoteVideoStats }) => void): void

获取远端视频流属性

参数

RemoteVideoStats详情

renewToken

renewToken(token: string, onSuccess?: () => void, onFailure?: (err: Error) => void): promise

更新校验 token

参数

返回值

promise

注意

进入房间时传入的校验 token 有过期时间，一旦触发 token 过期，会收到 token-request 事件，请在收到此事件后重新生成 token 然后调用此函数。

setLiveTranscoding

setLiveTranscoding(liveTranscoding: object): void

设置直播推流转码

参数

liveTranscoding属性设置

liveTranscoding设置示例

var LiveTranscoding = {
  width: 640,
  height: 360,
  videoBitrate: 400,
  videoFramerate: 15,
  audioSampleRate: 48000,
  audioBitrate: 48,
  audioChannels: 1,
  videoGop: 30,
  transcodingUsers,
  backgroundColor: 0x000000
};

transcodingUsers设置

注意

请在调用 startLiveStreaming 前调用此参数。

startLiveStreaming

startLiveStreaming(url: string, enableTranscoding: boolean, onSuccess: () => void, onFailure: (err: Error) => void): void

开启转推直播，推流到 CDN 成功开启转推后，请监听 live-transcoding-result 回调，如果转推过程中发生异常，等待服务端推流恢复，超时（60s）后，请调用 stopLiveStreaming 参数

stopLiveStreaming

stopLiveStreaming(onSuccess: () => void, onFailure: (err: Error) => void): void

停止转推直播

参数

sendCustomMessage

sendCustomMessage(message: string｜Object, onSuccess?: () => void, onFailure?: (err: Error) => void): promise

本地用户发送消息，房间内其他用户都将收到

参数

返回值

promise

sendMessageToUser

sendMessageToUser(uid: string｜Object, message: object): promise

向指定用户发送消息

参数

返回值

promise

setBusinessId

setBusinessId(id: string, onFailure?: (err: Error) => void): void

设置业务 ID ，一般用于区分相同项目中的不同业务线

参数

getBusinessId

getBusinessId(): string

获取业务 ID

返回值

业务 ID

enableAudioVolumeIndicator

client.enableAudioVolumeIndicator();

开启说话者音量提示 参数 无

返回值 promise

enableAutoSubscribe

(options?: { audio: boolean; video: boolean; }) => boolean

自动订阅音频流，默认为自动订阅。 进房前，你可以调用本接口修改订阅设置，如果进房后调用会失败。

返回值

是否调用成功

• true：方法调用成功
• false：方法调用失败

参数

| options | { audio: boolean; video: boolean; } | 开始自动订阅的参数，其中，视频流包含了摄像头流和屏幕流

setUserVisibility

(visibility: boolean) => Promise<any>

设置用户可见性。默认可见。 通过设置用户的可见性，可以控制用户在房间内的行为：

• 能否发布音视频流；
• 用户自身是否在房间中隐身。

注意

• 该方法在加入房间前后均可调用。
• 在房间内调用此方法，房间内其他用户会收到相应的回调通知：
• 从 false 切换至 true 时，房间内其他用户会监听到 peer-online 事件；
• 从 true 切换至 false 时，房间内其他用户会监听到 peer-leave 事件。
• 若调用该方法将可见性设为 false，此时尝试发布流会收到 NO_PUBLISH_PERMISSION 错误码。

参数

Stream

Stream 接口提供的方法用于定义音视频流对象的行为，例如流的播放控制、音视频的编码配置等。

你可以通过 createStream 创建 stream 对象。一个 stream 对象指通话中发布的本地音视频流或订阅的远端音视频流。

成员函数

函数说明

init

init(onSuccess?: () => void, onFailure?: (err: Error) => void): void

流初始化

参数

注意

后续操作都需要以此函数调用为前提。

play

play(domID: string, option?: object, onFailure?: (err: Error) => void): void

播放媒体流

参数

option详情

getMediaStream

getMediaStream(): mediaStream

获取媒体流

返回值

mediaStream

setVideoBitRate

setVideoBitRate(bitrate: array): void

设置视频码率

参数

注意

1.码率设置会有一个缓步上升的过程，慢慢达到目标值。

2.如果范围设置比较窄，实际效果并不很精确。

3.请在 publish 之前调用此方法。

setVideoProfile

setVideoProfile(profile: string): void

设置视频属性，设置本地流的视频编码属性。每个属性对应一套视频参数，如分辨率、帧率、码率等

参数

profile规格

注意

1.码率，帧率和分辨率设置会有一个缓步上升的过程，慢慢达到目标值。

2.请在 publish 之前调用此方法。

setVideoEncoderConfiguration

setVideoEncoderConfiguration(option: object): void

自定义视频编码配置，可以根据需要灵活设置本地流的视频分辨率、帧率和码率

参数

option详情

option示例

stream.setVideoEncoderConfiguration({
  // 视频分辨率
  resolution: {
    width: 640,
    height: 480
  },
  // 视频编码帧率。通常建议是 15 帧，不超过 30 帧
  frameRate: {
    min: 15,
    max: 30
  },
  // 码率。一般情况下推荐使用标准码率
  bitrate: {
    min: 1000,
    max: 5000
  }
});

注意

1.码率，帧率和分辨率设置会有一个缓步上升的过程，慢慢达到目标值。

2.请在 publish 之前调用此方法。

getStats

(callback: (stats: LocalStreamStats | RemoteStreamStats) => void) => void

获取到统计触发的回调 * 当获取的是发布音视频流时，数据为 LocalStreamStats * 当获取的是订阅的音视频流时，数据为 RemoteStreamStats

参数

LocalStreamStats 详情

RemoteStreamStats 详请

stop

stop(): void

停止播放，但不断开 RTC 连接

close

close(): void

关闭视频流或音频流，停止推拉流，断开 RTC 连接，取消摄像头和麦克风的访问权限并清除媒体流属性

muteAudio

muteAudio(): boolean

关闭音频

返回值

true: 成功
false: 失败

muteVideo

muteVideo(): boolean

关闭视频

返回值

true: 成功
false: 失败

unmuteAudio

unmuteAudio(): void

开启音频

返回值

true: 成功
false: 失败

unmuteVideo

unmuteVideo(): boolean

关闭视频

返回值

true: 成功
false: 失败

getId

getId(): string

获取流 ID

返回值

当前流的 ID

hasAudio

hasAudio(): boolean

获取音频 flag

返回值

true：当前流有音频数据

false：当前流没有音频数据

hasVideo

hasVideo(): boolean

获取视频 flag

返回值

true：当前流有视频数据

false：当前流没有视频数据

replaceTrack

replaceTrack(mediaStreamTrack: mediaStreamTrack, onSuccess?: () => void, onFailure?: (err: Error) => void): void

替换媒体流里面的音频或者视频轨

参数

注意

mediaStreamTrack 为浏览器原生 API。

getAudioLevel

getAudioLevel(): number

获取当前音频能量（可以理解为音量）

返回值

number：取值范围 0 - 255

注意

该方法获取的是当前时刻的音量。如果想表示本地或远端音量的变化，建议使用 Web API 中的 setTimeout 或者 setInterval 方法实时获取。

startAudioMixing

(options: MixOption, callback?: (error?: Error) => void) => void

开始播放音乐文件及混音 将指定音频文件和麦克风采集的音频流进行混音或用音频文件替换麦克风采集的音频流。可以通过多次调用本方法，传入不同的 ID 和 file_path 以实现同时播放多个音乐文件。

注意

• 开始播放音乐文件及混音后，可以调用 StopAudioMixing 方法停止播放音乐文件。
• 本方法混音数据来源于外部文件，而 EnableAudioMixingbuffer 的混音数据来源于外部缓存且音频格式为 PCM；这两种混音方式可以共存。

参数

options 详情

使用示例

stream.startAudioMixing({
    filePath: 'example.mp3',
    playTime: 0,
    loop: true
}, function(error) {
    if (error) {
        // 错误处理
        return;
    }
    // 播放成功后的流程
});

注意

支持浏览器：Safari 12 及以上版本，Chrome 65 及以上版本以及最新版 Firefox 。

stopAudioMixing

(id: number, callback?: (err: Error) => void) => void

停止播放音乐文件及混音

注意

• 调用 startAudioMixing 方法开始播放音乐文件及混音后，可以调用本方法停止播放音乐文件及混音。

参数

pauseAudioMixing

(id: number, callback?: () => void) => Promise<void>

暂停播放音乐文件及混音

注意

• 调用 StartAudioMixing 方法开始播放音乐文件及混音后，可以通过调用本方法暂停播放音乐文件及混音。
• 调用本方法暂停播放音乐文件及混音后，可调用 ResumeAudioMixing 方法恢复播放及混音。

参数

resumeAudioMixing

(id: number, callback?: (err?: Error) => void) => Promise<void>

恢复播放音乐文件及混音

注意 调用 PauseAudioMixing 方法暂停播放音乐文件及混音后，可以通过调用本方法恢复播放及混音。

参数

getAudioMixingDuration

(id: number) => number

获取音乐文件总时长

注意 调用本方法前，需要先调用 PreloadAudioMixing 或 StartAudioMixing。

返回值

音乐文件总时长

• >0: 成功, 音乐文件时长，单位为毫秒。
• <0: 失败

参数

getAudioMixingCurrentPosition

(id: number) => number

获取音乐文件播放进度

注意 调用本方法前，需要先调用 StartAudioMixing。

返回值

音乐文件播放进度

• >0: 成功, 音乐文件时长，单位为毫秒。
• <0: 失败

参数

setAudioMixingPosition

(id: number, targetTime: number, callbackOrigin?: () => void) => Promise<void>

设置音乐文件音频文件的播放位置 你可以根据实际情况从指定的位置播放音乐文件，无需从头到尾完整播放一个音乐文件。

注意 调用本方法前，需要先调用 StartAudioMixing。

参数

setAudioMixingVolume

(id: number, volume: number) => void

调节音乐文件在本地和远端播放的音量大小

注意 调用本方法前，需要先调用 PreloadAudioMixing 或 StartAudioMixing。

参数

preloadAudioMixing

(id: string, filePath: string) => Promise<void>

预加载指定音乐文件到缓存 需要频繁播放某个音乐文件的时候，调用本方法预加载该文件，在播放的时候可以只加载一次该文件，减少 CPU 占用。

注意

• 本方法只是预加载指定音乐文件，只有调用 startAudioMixing 方法才开始播放指定音乐文件。
• 调用本方法预加载的指定音乐文件可以通过 unloadAudioMixing 卸载。

参数

unloadAudioMixing

(id: string) => Promise<void>

清除预加载的音频资源

参数

enableAudioMixingBuffer

(callback?: () => void) => void

启动外部音频流混音

注意

• 必须先调用本方法启动外部音频流混音，随后调用 PushAudioMixingBuffer 方法，才能向 SDK 推送外部音频帧数据。
• 本方法的混音数据来源于外部缓存且音频格式为 PCM；而 StartAudioMixing 的混音数据来源于外部文件，支持的文件格式有: mp3，aac等；这两种混音方式可以共存。
• 该方法启动的外部音频流混音不支持音量调节，暂停和恢复操作。
• 如要关闭外部音频流混音，请使用 DisableAudioMixingBuffer。

参数

disableAudioMixingBuffer

() => void

关闭外部音频流混音

注意 使用 EnableAudioMixingBuffer 开启外部音频流混音后，请使用本方法关闭该混音。

pushAudioMixingBuffer

(buffer: ArrayBuffer) => void

向 SDK 推送外部音频数据

注意 调用该方法前，须通过 EnableAudioMixingBuffer 启动外部音频流混音。

参数

getVideoTrack

getVideoTrack(): mediaStreamTrack

获取当前流中的视频轨道

返回值

视频轨道

注意

mediaStreamTrack 为浏览器原生 API。

getAudioTrack

getAudioTrack(): mediaStreamTrack

获取当前流中的音频轨道

返回值

音频轨道

注意

mediaStreamTrack 为浏览器原生 API。

mirror

mirror(enabled: boolean): void

开启/关闭本地摄像头流预览的镜像模式。

参数

注意 调用此接口设置不会对发布到远端的视频流进行镜像处理。

enableLocalVideo

enableLocalVideo = (enable: boolean, constraints?: MediaTrackConstraints) => boolean

开启/关闭视频采集设备

参数

返回值 true：成功 false：失败

enableLocalAudio

enableLocalAudio = (enable: boolean, constraints?: MediaTrackConstraints) => boolean

开启/关闭音频采集设备

参数

返回值 true：成功 false：失败

switchDevice

switchDevice: ({microphoneId?: string, camerId?: string}) => boolean

在 createStream 之后，可以调用该方法切换本地流的媒体输入设备，包括：音频输入设备（如麦克风）和视频输入设备（如摄像头）

参数

注意 设备 ID 可通过 getDevices 获取

返回值 true：成功 false：失败

setScreenParameters

setScreenParameters({
        width?: number，
        height?: number，
        frameRate?: number，
        bitrate?: number
})

在调用 stream.init 之前，调用本接口设置共享屏幕属性，分别设置屏幕分辨率，帧率和码率。

参数

• width 和 height 必须同时存在，否则由浏览器自行配置默认值。
• 分辨率、帧率属性使用 ideal 的方式设置，即浏览器根据自身能力，动态调整分辨率和帧率。
• width，height，frameRate，bitrate 没设置的话，由浏览器自行配置
  • width、height：通常为被分享画面的实际宽高
  • frameRate ：由浏览器自动适配
  • bitrate ：不受限，由浏览器自动适配
• 如果width、height、frameRate 都设置了，但是 bitrate 没设置，SDK 会在内部自动计算码率。

返回值 无

注意 * 由于设备和浏览器的限制，设置成功后浏览器可能按照实际能力自动调整和适配 * 使用 Safari 浏览器时，如果设置的分辨率比例跟屏幕比例不一致会出现剪裁。

sendSEIMessage

(sei: Uint8Array, repeatCount?: number) => void

在视频通信时，通过视频帧发送 SEI 数据。

注意

• 你可以通过此接口对 RTC SDK 内部采集的视频帧添加 SEI。
• 如果调用此接口之后的 2s 内，没有可带 SEI 的视频帧（比如没有开启视频采集和传输），那么，SEI 数据不会被加进视频帧中。
• 消息发送成功后，远端会收到 sei-received 事件。

参数

Logger

VRTC.Logger

提供设置 logger 的方法，包括设置日志输出等级、开启/关闭日志上传。

成员常量

成员函数

函数说明

setLogLevel

设置日志输出等级

setLogLevel(level: LogLevel): void

参数

注意

1.LogLevel 为 logger 成员常量：VERBOSE ，DEBUG ，TRACE ，INFO ，WARNING ，ERROR ，NONE

2.默认输出等级为 WARNING 。

3.LogLevel 中各个等级日志输出量递减。